Claude Code 跳过登录 / 免交互认证配置指南

适用场景：企业内部网关（如 LiteLLM Gateway）部署，需要 Claude Code 跳过 /login 交互式登录，直接使用 API Key / 自建网关完成认证。

0. 核心概念（先搞懂两个文件）

Claude Code 涉及两个完全不同的配置文件，很多问题都是把它们搞混导致的：

另外还有项目级配置：

• .claude/settings.json（项目内，随仓库提交，团队共享）
• .claude/settings.local.json（项目内，不提交，个人覆盖）

跳过登录需要两件事同时满足：

1. ~/.claude.json 里 hasCompletedOnboarding: true → 跳过"选择登录方式"的交互式问题
2. 有效的认证凭据（环境变量或 settings.json 里的 env）→ 让 Claude Code 真正认为自己"已认证"，而不是走到某一步又回退到 /login

只做第 1 步、没做第 2 步，就会出现你截图里那种 Not logged in · Please run /login 的报错。

1. 通用配置内容（三系统通用，仅路径不同）

1.1 设置环境变量（推荐做法：写入 settings.json）

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key",
    "ANTHROPIC_MODEL": "your-model-alias"
  }
}

说明：

• 如果网关走的是标准 Anthropic 兼容协议（x-api-key 头），用 ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 均可，具体取决于你网关的鉴权方式（Bearer token 用 ANTHROPIC_AUTH_TOKEN，raw API key 用 ANTHROPIC_API_KEY，两者不要同时设置，容易冲突触发"mixed auth"警告）。
• settings.json 里的 env 会覆盖系统环境变量，比直接 export/系统变量更稳定，推荐团队分发统一用这种方式。

1.2 跳过 onboarding（写入 .claude.json）

在 ~/.claude.json 最外层加上：

{
  "hasCompletedOnboarding": true
}

如果文件已存在其他内容，注意用逗号隔开，不要破坏 JSON 结构。

1.3（可选）预置项目信任，跳过 "Do you trust this folder" 弹窗

{
  "hasCompletedOnboarding": true,
  "projects": {
    "/path/to/project": {
      "hasTrustDialogAccepted": true
    }
  }
}

Windows 路径注意用双反斜杠转义，如 "C:\\Users\\yj\\projects\\myrepo"。

2. 分系统操作步骤

2.1 macOS

# 1. 创建 settings.json 目录（如果不存在）
mkdir -p ~/.claude

# 2. 写入认证配置
cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key"
  }
}
EOF

# 3. 跳过 onboarding（用 python3 安全合并 JSON，避免手写破坏已有内容）
python3 -c "
import json, os
p = os.path.expanduser('~/.claude.json')
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg['hasCompletedOnboarding'] = True
json.dump(cfg, open(p, 'w'), indent=2)
"

# 4. 验证环境变量确实生效
env | grep ANTHROPIC

# 5. 启动
claude

如果用 zsh 且想让变量对所有终端生效（不推荐用于团队分发，仅个人调试用）：

echo 'export ANTHROPIC_BASE_URL="https://your-gateway.example.com"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="sk-your-gateway-key"' >> ~/.zshrc
source ~/.zshrc

2.2 Ubuntu / Linux

步骤与 macOS 基本一致，路径相同（~ 即 /home/<user>）：

mkdir -p ~/.claude

cat > ~/.claude/settings.json << 'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key"
  }
}
EOF

python3 -c "
import json, os
p = os.path.expanduser('~/.claude.json')
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg['hasCompletedOnboarding'] = True
json.dump(cfg, open(p, 'w'), indent=2)
"

env | grep ANTHROPIC
claude

容器 / 无人值守部署（headless）额外说明：

如果是在 Docker 容器或 CI 环境里跑 Claude Code，建议启动脚本里显式写死环境变量，而不是依赖 shell rc 文件（容器里往往不会 source 这些文件）：

#!/bin/bash
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-gateway-key"

python3 -c "
import json
config = {
    'hasCompletedOnboarding': True,
    'projects': {'/workspace/project': {'hasTrustDialogAccepted': True}}
}
json.dump(config, open('/root/.claude.json', 'w'))
"

claude --dangerously-skip-permissions -p "你的任务指令"

注意：--dangerously-skip-permissions 首次使用仍会弹一个安全确认，这个目前无法通过配置文件预置跳过，headless 场景需要用 tmux + 自动按键脚本处理，或改用 apiKeyHelper 方案动态取 token。

2.3 Windows

Windows 下 .claude.json 位于用户目录：%USERPROFILE%\.claude.json（通常是 C:\Users\你的用户名\.claude.json）。

方式一：PowerShell

# 1. 创建目录
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude" | Out-Null

# 2. 写入 settings.json
@'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://your-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-gateway-key"
  }
}
'@ | Set-Content -Path "$env:USERPROFILE\.claude\settings.json" -Encoding UTF8

# 3. 跳过 onboarding
python -c "
import json, os
p = os.path.expanduser('~/.claude.json')
cfg = json.load(open(p)) if os.path.exists(p) else {}
cfg['hasCompletedOnboarding'] = True
json.dump(cfg, open(p, 'w'), indent=2)
"

# 4. 验证
Get-ChildItem Env:ANTHROPIC*

# 5. 启动
claude

如果想让环境变量长期生效（写入用户环境变量，重启终端后依然有效）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-gateway.example.com", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "sk-your-gateway-key", "User")

设置后需要重新打开终端才会生效（当前窗口读取的是旧的环境变量快照）。

方式二：Git Bash（如果你团队统一用 Git Bash 跑 Claude Code）

和 macOS/Linux 步骤几乎一致，直接复用 2.1 节的 bash 命令即可，~ 会被 Git Bash 正确解析为 $USERPROFILE。

3. 常见报错排查表

4. 团队批量分发建议

如果要给团队所有人统一免登录接入网关，建议：

1. 把 settings.json 模板和 .claude.json 的 onboarding/trust 预置脚本一起打包进你现在维护的部署工具（VSCode 扩展 / 初始化脚本）里，做成一键执行。
2. 环境变量优先走 settings.json 的 env 字段而不是让每个人手动 export，减少"系统变量覆盖"类问题。
3. 保留一份"重置脚本"，遇到状态污染（登录态/API Key 混用）时可以一键备份并重建 .claude.json，避免大家各自手动删文件排查半天。

# 重置脚本示例（Linux/macOS）
cp ~/.claude.json ~/.claude.json.bak.$(date +%s) 2>/dev/null
python3 -c "
import json
json.dump({'hasCompletedOnboarding': True}, open('$HOME/.claude.json', 'w'), indent=2)
"
echo "已重置 .claude.json，请重新启动 claude"

5. 免责声明

• hasCompletedOnboarding 等字段属于社区实践总结，未见于官方文档，不同版本行为可能有调整（历史上出现过忽略该配置的回归 bug），升级 Claude Code 后如遇异常建议重新验证本文步骤是否仍适用。
• 官方文档参考：https://code.claude.com/docs/en/settings